Amiga Plus 2002 #11

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Plus 2002 #11 / Amiga Plus CD - 2002 - No. 11.iso / Tools / Freeware / BasiliskII-1.0 / TECH < prev next >

Wrap

Text File | 2002-09-06 | 32.4 KB | 608 lines

BASILISK II TECHNICAL MANUAL ============================ 0. Table of Contents -------------------- 1. Introduction 2. Modes of operation 3. Memory access 4. Calling native routines from 68k mode and vice-versa 5. Interrupts 6. Parts of Basilisk II 7. Porting Basilisk II 1. Introduction --------------- Basilisk II can emulate two kind of Macs, depending on the ROM being used: 1. A Mac Classic 2. A Mac II series computer ("Mac II series" here means all 68020/30/40 based Macs with 32-bit clean ROMs (this excludes the original Mac II, the IIx/IIcx and the SE/030), except PowerBooks; in the following, "Mac II" is used as an abbreviation of "Mac II series computer", as defined above) More precisely spoken, MacOS under Basilisk II behaves like on a Mac Classic or Mac II because, apart from the CPU, the RAM and the ROM, absolutely no Mac hardware is emulated. Rather, Basilisk II provides replacements (usually in the form of MacOS drivers) for the parts of MacOS that access hardware. As there are practically no Mac applications that access hardware directly (this is also due to the fact that the hardware of different Mac models is sometimes as different as, say, the hardware of an Atari ST and an Amiga 500), both the compatibility and speed of this approach are very high. 2. Modes of operation --------------------- Basilisk II is designed to run on many different hardware platforms and on many different operating systems. To provide optimal performance under all environments, it can run in four different modes, depending on the features of the underlying environment (the modes are selected with the REAL_ADDRESSING, DIRECT_ADDRESSING and EMULATED_68K defines in "sysdeps.h"): 1. Emulated CPU, "virtual" addressing (EMULATED_68K = 1, REAL_ADDRESSING = 0): This mode is designed for non-68k or little-endian systems or systems that don't allow accessing RAM at 0x0000..0x1fff. This is also the only mode that allows 24-bit addressing, and thus the only mode that allows Mac Classic emulation. The 68k processor is emulated with the UAE CPU engine and two memory areas are allocated for Mac RAM and ROM. The memory map seen by the emulated CPU and the host CPU are different. Mac RAM starts at address 0 for the emulated 68k, but it may start at a different address for the host CPU. In order to handle the particularities of each memory area (RAM, ROM and Frame Buffer), the address space of the emulated 68k is broken down into banks. Each bank is associated with a series of pointers to specific memory access functions that carry out the necessary operations (e.g. byte-swapping, catching illegal writes to memory). A generic memory access function, get_long() for example, goes through the table of memory banks (mem_banks) and fetches the appropriate specific memory access fonction, lget() in our example. This slows down the emulator, of course. 2. Emulated CPU, "direct" addressing (EMULATED_68K = 1, DIRECT_ADDRESSING = 1): As in the virtual addressing mode, the 68k processor is emulated with the UAE CPU engine and two memory areas are set up for RAM and ROM. Mac RAM starts at address 0 for the emulated 68k, but it may start at a different address for the host CPU. Besides, the virtual memory areas seen by the emulated 68k are separated by exactly the same amount of bytes as the corresponding memory areas allocated on the host CPU. This means that address translation simply implies the addition of a constant offset (MEMBaseDiff). Therefore, the memory banks are no longer used and the memory access functions are replaced by inline memory accesses. 3. Emulated CPU, "real" addressing (EMULATED_68K = 1, REAL_ADDRESSING = 1): This mode is intended for non-68k systems that do allow access to RAM at 0x0000..0x1fff. As in the virtual addressing mode, the 68k processor is emulated with the UAE CPU engine and two areas are allocated for RAM and ROM but the emulated CPU lives in the same address space as the host CPU. This means that if something is located at a certain address for the 68k, it is located at the exact same address for the host CPU. Mac addresses and host addresses are the same. The memory accesses of the CPU emulation still go through access functions but the address translation is no longer needed. The memory access functions are replaced by direct, inlined memory accesses, making for the fastest possible speed of the emulator. On little-endian systems, byte-swapping is still required, of course. A usual consequence of the real addressing mode is that the Mac RAM doesn't any longer begin at address 0 for the Mac and that the Mac ROM also is not located where it usually is on a real Mac. But as the Mac ROM is relocatable and the available RAM is defined for MacOS by the start of the system zone (which is relocated to the start of the allocated RAM area) and the MemTop variable (which is also set correctly) this is not a problem. There is, however, one RAM area that must lie in a certain address range. This area contains the Mac "Low Memory Globals" which (on a Mac II) are located at 0x0000..0x1fff and which cannot be moved to a different address range. The Low Memory Globals constitute of many important MacOS and application global variables (e.g. the above mentioned "MemTop" variable which is located at 0x0108). For the real addressing mode to work, the host CPU needs access to 0x0000..0x1fff. Under most operating systems, this is a big problem. On some systems, patches (like PrepareEmul on the Amiga or the sheep_driver under BeOS) can be installed to "open up" this area. On other systems, it might be possible to use access exception handlers to emulate accesses to this area. But if the Low Memory Globals area cannot be made available, using the real addressing mode is not possible. Note: currently, real addressing mode is known to work only on AmigaOS, NetBSD/m68k, and Linux/i386. 4. Native CPU (EMULATED_68K = 0, this also requires REAL_ADDRESSING = 1) This mode is designed for systems that use a 68k (68020 or better) processor as host CPU and is the technically most difficult mode to handle. The Mac CPU is no longer emulated (the UAE CPU emulation is not needed) but MacOS and Mac applications run natively on the existing 68k CPU. This means that the emulator has its maximum possible speed (very close to that of a real Mac with the same CPU). As there is no control over the memory accesses of the CPU, real addressing mode is implied, and so the Low Memory area must be accessible (an MMU might be used to set up different address spaces for the Mac and the host, but this is not implemented in Basilisk II). The native CPU mode has some possible pitfalls that might make its implementation difficult on some systems: a) Implied real addressing (this also means that Mac programs that go out of control can crash the emulator or the whole system) b) MacOS and Mac applications assume that they always run in supervisor mode (more precisely, they assume that they can safely use certain priviledged instructions, mostly for interrupt control). So either the whole emulator has to be run in supervisor mode (which usually is not possible on multitasking systems) or priviledged instructions have to be trapped and emulated. The Amiga and NetBSD/m68k versions of Basilisk II use the latter approach (it is possible to run supervisor mode tasks under the AmigaOS multitasking kernel (ShapeShifter does this) but it requires modifying the Exec task switcher and makes the emulator more unstable). c) On multitasking systems, interrupts can usually not be handled as on a real Mac (or with the UAE CPU). The interrupt levels of the host will not be the same as on a Mac, and the operating systems might not allow installing hardware interrupt handlers or the interrupt handlers might have different stack frames and run-time environments than 68k hardware interrupts. The usual solution is to use some sort of software interrupts or signals to interrupt the main emulation process and to manually call the Mac 68k interrupt handler with a faked stack frame. d) 68060 systems are a small problem because there is no Mac that ever used the 68060 and MacOS doesn't know about this processor. Basilisk II reports the 68060 as being a 68040 to the MacOS and patches some places where MacOS makes use of certain 68040-specific features such as the FPU state frame layout or the PTEST instruction. Also, Basilisk II requires that all of the Motorola support software for the 68060 to emulate missing FPU and integer instructions and addressing modes is provided by the host operating system (this also applies to the 68040). e) The "EMUL_OP" mechanism described below requires the interception and handling of certain emulator-defined instructions. 3. Memory access ---------------- There is often a need to access Mac RAM and ROM inside the emulator. As Basilisk II may run in "real" or "virtual" addressing mode on many different architectures, big-endian or little-endian, certain platform-independent data types and functions are provided: a) "sysdeps.h" defines the types int8, uint8, int16, uint16, int32 and uint32 for numeric quantities of a certain signedness and bit length b) "cpu_emulation.h" defines the ReadMacInt*() and WriteMacInt*() functions which should always be used to read from or write to Mac RAM or ROM c) "cpu_emulation.h" also defines the Mac2HostAddr() function that translates a Mac memory address to a (uint8 *) in host address space. This allows you to access larger chunks of Mac memory directly, without going through the read/write functions for every access. But doing so you have to perform any needed endianess conversion of the data yourself by using the ntohs() etc. macros which are available on most systems or defined in "sysdeps.h". 4. Calling native routines from 68k mode and vice-versa ------------------------------------------------------- An emulator like Basilisk II requires two kinds of cross-platform function calls: a) Calling a native routine from the Mac 68k context b) Calling a Mac 68k routine from the native context Situation a) arises in nearly all Basilisk drivers and system patches while case b) is needed for the invocation of Mac call-back or interrupt routines. Basilisk II tries to solve both problems in a way that provides the same interface whether it is running on a 68k or a non-68k system. 4.1. The EMUL_OP mechanism -------------------------- Calling native routines from the Mac 68k context requires breaking out of the 68k emulator or interrupting the current instruction flow and is done via unimplemented 68k opcodes (called "EMUL_OP" opcodes). Basilisk II uses opcodes of the form 0x71xx (these are invalid MOVEQ opcodes) which are defined in "emul_op.h". When such an opcode is encountered, whether by the emulated CPU or a real 68k, the execution is interrupted, all CPU registers saved and the EmulOp() function from "emul_op.cpp" is called. EmulOp() decides which opcode caused the interrupt and performs the required actions (mostly by calling other emulator routines). The EMUL_OP handler routines have access to nearly all of the 68k user mode registers (exceptions being the PC, A7 and SR). So the EMUL_OP opcodes can be thought of as extensions to the 68k instruction set. Some of these opcodes are used to implement ROM or resource patches because they only occupy 2 bytes and there is sometimes not more room for a patch. 4.2. Execute68k() ----------------- "cpu_emulation.h" declares the functions Execute68k() and Execute68kTrap() to call Mac 68k routines or MacOS system traps from inside an EMUL_OP handler routine. They allow setting all 68k user mode registers (except PC and SR) before the call and examining all register contents after the call has returned. EMUL_OP and Execute68k() may be nested, i.e. a routine called with Execute68k() may contain EMUL_OP opcodes and the EMUL_OP handlers may in turn call Execute68k() again. 5. Interrupts ------------- Various parts of Basilisk II (such as the Time Manager and the serial driver) need an interrupt facility to trigger asynchronous events. The MacOS uses different 68k interrupt levels for different events, but for simplicity Basilisk II only uses level 1 and does it's own interrupt dispatching. The "InterruptFlags" contains a bit mask of the pending interrupts. These are the currently defined interrupt sources (see main.h): INTFLAG_60HZ - MacOS 60Hz interrupt (unlike a real Mac, we also handle VBL interrupts and the Time Manager here) INTFLAG_1HZ - MacOS 1Hz interrupt (updates system time) INTFLAG_SERIAL - Interrupt for serial driver I/O completion INTFLAG_ETHER - Interrupt for Ethernet driver I/O completion and packet reception INTFLAG_AUDIO - Interrupt for audio "next block" requests INTFLAG_TIMER - Reserved for a future implementation of a more precise Time Manager (currently not used) INTFLAG_ADB - Interrupt for mouse/keyboard input INTFLAG_NMI - NMI for debugging (not supported on all platforms) An interrupt is triggered by calling SetInterruptFlag() with the desired interrupt flag constant and then TriggerInterrupt(). When the UAE 68k emulator is used, this will signal a hardware interrupt to the emulated 680x0. On a native 68k machine, some other method for interrupting the MacOS thread has to be used (e.g. on AmigaOS, a signal exception is used). Care has to be taken because with the UAE CPU, the interrupt will only occur when Basilisk II is executing MacOS code while on a native 68k machine, the interrupt could occur at any time (e.g. inside an EMUL_OP handler routine). In any case, the MacOS thread will eventually end up in the level 1 interrupt handler which contains an M68K_EMUL_OP_IRQ opcode. The opcode handler in emul_op.cpp will then look at InterruptFlags and decide which routines to call. 6. Parts of Basilisk II ----------------------- The conception of Basilisk II is quite modular and consists of many parts which are relatively independent from each other: - UAE CPU engine ("uae_cpu/*", not needed on all systems) - ROM patches ("rom_patches.cpp", "slot_rom.cpp" and "emul_op.cpp") - resource patches ("rsrc_patches.cpp" and "emul_op.cpp") - PRAM Utilities replacement ("xpram.cpp") - ADB Manager replacement ("adb.cpp") - Time Manager replacement ("timer.cpp") - SCSI Manager replacement ("scsi.cpp") - video driver ("video.cpp") - audio component ("audio.cpp") - floppy driver ("sony.cpp") - disk driver ("disk.cpp") - CD-ROM driver ("cdrom.cpp") - external file system ("extfs.cpp") - serial drivers ("serial.cpp") - Ethernet driver ("ether.cpp") - system-dependant device access ("sys_*.cpp") - user interface strings ("user_strings.cpp") - preferences management ("prefs.cpp" and "prefs_editor_*.cpp") Most modules consist of a platform-independant part (such as video.cpp) and a platform-dependant part (such as video_beos.cpp). The "dummy" directory contains generic "do-nothing" versions of some of the platform-dependant parts to aid in testing and porting. 6.1. UAE CPU engine ------------------- All files relating to the UAE 680x0 emulation are kept in the "uae_cpu" directory. The "cpu_emulation.h" header file defines the link between the UAE CPU and the rest of Basilisk II, and "basilisk_glue.cpp" implements the link. It should be possible to replace the UAE CPU with a different 680x0 emulation by creating a new "xxx_cpu" directory with an appropriate "cpu_emulation.h" header file (for the inlined memory access functions) and writing glue code between the functions declared in "cpu_emulation.h" and those provided by the 680x0 emulator. 6.2. ROM and resource patches ----------------------------- As described above, instead of emulating custom Mac hardware, Basilisk II provides replacements for certain parts of MacOS to redirect input, output and system control functions of the Mac hardware to the underlying operating systems. This is done by applying patches to the Mac ROM ("ROM patches") and the MacOS system file ("resource patches", because nearly all system software is contained in MacOS resources). Unless resources are written back to disk, the system file patches are not permanent (it would cause many problems if they were permanent, because some of the patches vary with different versions of Basilisk II or even every time the emulator is launched). ROM patches are contained in "rom_patches.cpp" and resource patches are contained in "rsrc_patches.cpp". The ROM patches are far more numerous because nearly all the software needed to run MacOS is contained in the Mac ROM (the system file itself consists mainly of ROM patches, in addition to pictures and text). One part of the ROM patches involves the construction of a NuBus slot declaration ROM (in "slot_rom.cpp") which is used to add the video and Ethernet drivers. Apart from the CPU emulation, the ROM and resource patches contain most of the "logic" of the emulator. 6.3. PRAM Utilities ------------------- MacOS stores certain nonvolatile system parameters in a 256 byte battery backed-up CMOS RAM area called "Parameter RAM", "PRAM" or "XPRAM" (which refers to "Extended PRAM" because the earliest Mac models only had 20 bytes of PRAM). Basilisk II patches the ClkNoMem() MacOS trap which is used to access the XPRAM (apart from some routines which are only used early during system startup) and the real-time clock. The XPRAM is emulated in a 256 byte array which is saved to disk to preserve the contents for the next time Basilisk is launched. 6.4. ADB Manager ---------------- For emulating a mouse and a keyboard, Basilisk II patches the ADBOp() MacOS trap. Platform-dependant code reports mouse and keyboard events with the ADBMouseDown() etc. functions where they are queued, and the INTFLAG_ADB interrupt is triggered. The ADBInterrupt() handler function sends the input events to MacOS by calling the ADB mouse and keyboard handlers with Execute68k(). 6.5. Time Manager ----------------- Basilisk II completely replaces the Time Manager (InsTime(), RmvTime(), PrimeTime() and Microseconds() traps). A "TMDesc" structure is associated with each Time Manager task, that contains additional data. The tasks are executed in the TimerInterrupt() function which is currently called inside the 60Hz interrupt handler, thus limiting the resolution of the Time Manager to 16.6ms. 6.6. SCSI Manager ----------------- The (old-style) SCSI Manager is also completely replaced and the MacOS SCSIDispatch() trap redirected to the routines in "scsi.cpp". Under the MacOS, programs have to issue multiple calls for all the different phases of a SCSI bus interaction (arbitration, selection, command transfer etc.). Basilisk II maps this API to an atomic API which is used by most modern operating systems. All action is deferred until the call to SCSIComplete(). The TIB (Transfer Instruction Block) mini-programs used by the MacOS are translated into a scatter/gather list of data blocks. Operating systems that don't support scatter/gather SCSI I/O will have to use buffering if more than one data block is being transmitted. Some more advanced (but rarely used) aspects of the SCSI Manager (like messaging and compare operations) are not emulated. 6.7. Video driver ----------------- The NuBus slot declaration ROM constructed in "slot_rom.cpp" contains a driver definition for a video driver. The Control and Status calls of this driver are implemented in "video.cpp". The host-side initialization of the video system is done in VideoInit(). This function must fill the VideoModes vector with a list of supported video modes (combinations of color depth and resolution). It must then call video_init_depth_list() and setup the VideoMonitor structure with the default mode information and the address of a frame buffer for MacOS. In real addressing mode, this frame buffer must be in a MacOS compatible layout (big-endian and 1, 2, 4 or 8 bits paletted chunky pixels, RGB 5:5:5 or xRGB 8:8:8:8). In virtual addressing mode, the frame buffer is located at address 0xa0000000 on the Mac side and you have to supply the host address, size and layout (BasiliskII will do an automatic pixel format conversion in virtual addressing mode) in the variables MacFrameBaseHost, MacFrameSize and MacFrameLayout. There are two functions of the platform-dependant video driver code that get called during runtime: video_set_palette() to update the CLUT (for indexed modes) or gamma table (for direct color modes), and video_switch_to_mode() to switch to a different color depth and/or resolution (in this case the frame buffer base in VideoMonitor must be updated). 6.8. Audio component -------------------- Basilisk II provides a Sound Manager 3.x audio component for sound output. Earlier Sound Manager versions that don't use components but 'snth' resources are not supported. Nearly all component functions are implemented in "audio.cpp". The system-dependant modules ("audio_*.cpp") handle the initialization of the audio hardware/driver, volume controls, and the actual sound output. The mechanism of sound output varies depending on the platform but usually there will be one "streaming thread" (either a thread that continuously writes data buffers to the audio device or a callback function that provides the next data buffer) that reads blocks of sound data from the MacOS Sound Manager and writes them to the audio device. To request the next data buffer, the streaming thread triggers the INTFLAG_AUDIO interrupt which will cause the MacOS thread to eventually call AudioInterrupt(). Inside AudioInterrupt(), the next data block will be read and the streaming thread is signalled that new audio data is available. 6.9. Floppy, disk and CD-ROM drivers ------------------------------------ Basilisk II contains three MacOS drivers that implement floppy, disk and CD-ROM access ("sony.cpp", "disk.cpp" and "cdrom.cpp"). They rely heavily on the functionality provided by the "sys_*.cpp" module. BTW, the name ".Sony" of the MacOS floppy driver comes from the fact that the 3.5" floppy drive in the first Mac models was custom-built for Apple by Sony (this was one of the first applications of the 3.5" floppy format which was also invented by Sony). 6.10. External file system -------------------------- Basilisk II also provides a method for accessing files and direcories on the host OS from the MacOS side by means of an "external" file system (henceforth called "ExtFS"). The ExtFS is built upon the File System Manager 1.2 interface that is built into MacOS 7.6 (and later) and available as a system extension for earlier MacOS versions. Unlike other parts of Basilisk II, extfs.cpp requires POSIX file I/O and this is not going to change any time soon, so if you are porting Basilisk II to a system without POSIX file functions, you should emulate them. 6.11. Serial drivers -------------------- Similar to the disk drivers, Basilisk II contains replacement serial drivers for the emulation of Mac modem and printer ports. To avoid duplicating code, both ports are handled by the same set of routines. The SerialPrime() etc. functions are mostly wrappers that determine which port is being accessed. All the real work is done by the "SERDPort" class which is subclassed by the platform-dependant code. There are two instances (for port A and B) of the subclasses. Unlike the disk drivers, the serial driver must be able to handle asynchronous operations. Calls to SerialPrime() will usually not actually transmit or receive data but delegate the action to an independant thread. SerialPrime() then returns "1" to indicate that the I/O operation is not yet completed. The completion of the I/O request is signalled by calling the MacOS trap "IODone". However, this can't be done by the I/O thread because it's not in the right run-time environment to call MacOS functions. Therefore it will trigger the INTFLAG_SERIAL interrupt which causes the MacOS thread to eventually call SerialInterrupt(). SerialInterrupt(), in turn, will not call IODone either but install a Deferred Task to do the job. The Deferred Task will be called by MacOS when it returns to interrupt level 0. This mechanism sounds complicated but is necessary to ensure stable operation of the serial driver. 6.12. Ethernet driver --------------------- A driver for Ethernet networking is also contained in the NuBus slot ROM. Only one ethernet card can be handled by Basilisk II. For Ethernet to work, Basilisk II must be able to send and receive raw Ethernet packets, including the 14-byte header (destination and source address and type/length field), but not including the 4-byte CRC. This may not be possible on all platforms or it may require writing special net drivers or add-ons or running with superuser priviledges to get access to the raw packets. For situations in which access to raw Ethernet packets is not possible, Basilisk II implements a special "tunneling" mode in which it sends and receives packets via UDP, using BSD socket functions. It simply wraps the Ethernet packets into UDP packets, using dummy Ethernet addresses that are made up of the IP address of the host. Ethernet broadcast and AppleTalk multicast packets are sent to the IP broadcast address. Because of this non-standard way of tunneling, it is only possible to set up a "virtual" network amongst machines running Basilisk II in this way. Writing packets works as in the serial drivers. The ether_write() routine may choose to send the packet immediately (e.g. under BeOS) and return noErr or to delegate the sending to a separate thread (e.g. under AmigaOS) and return "1" to indicate that the operation is still in progress. For the latter case, a Deferred Task structure is provided in the ether_data area to call IODone from EtherInterrupt() when the packet write is complete (see above for a description of the mechanism). Packet reception is a different story. First of all, there are two methods provided by the MacOS Ethernet driver API to read packets, one of which (ERead/ ERdCancel) is not supported by Basilisk II. Basilisk II only supports reading packets by attaching protocol handlers. This shouldn't be a problem because the only network code I've seen so far that uses ERead is some Apple sample code. AppleTalk, MacTCP, MacIPX, OpenTransport etc. all use protocol handlers. By attaching a protocol handler, the user of the Ethernet driver supplies a handler routine that should be called by the driver upon reception of Ethernet packets of a certain type. 802.2 packets (type/length field of 0..1500 in the packet header) are a bit special: there can be only one protocol handler attached for 802.2 packets (by specifying a packet type of "0"). The MacOS LAP Manager will attach a 802.2 handler upon startup and handle the distribution of 802.2 packets to sub-protocol handlers, but the Basilisk II Ethernet driver is not concerned with this. When the driver receives a packet, it has to look up the protocol handler installed for the respective packet type (if any has been installed at all) and call the packet handler routine. This must be done with Execute68k() from the MacOS thread, so an interrupt (INTFLAG_ETHER) is triggered upon reception of a packet so the EtherInterrupt() routine can call the protocol handler. Before calling the handler, the Ethernet packet header has to be copied to MacOS RAM (the "ed_RHA" field of the ether_data structure is provided for this). The protocol handler will read the packet data by means of the ReadPacket/ReadRest routines supplied by the Ethernet driver. Both routines will eventually end up in EtherReadPacket() which copies the data to Mac address space. EtherReadPacket() requires the host address and length of the packet to be loaded to a0 and d1 before calling the protocol handler. Does this sound complicated? You are probably right. Here is another description of what happens upon reception of a packet: 1. Ethernet card receives packet and notifies some platform-dependant entity inside Basilisk II 2. This entity will store the packet in some safe place and trigger the INTFLAG_ETHER interrupt 3. The MacOS thread will execute the EtherInterrupt() routine and look for received packets 4. If a packet was received of a type to which a protocol handler had been attached, the packet header is copied to ed_RHA, a0/d1 are loaded with the host address and length of the packet data, a3 is loaded with the Mac address of the first byte behing ed_RHA and a4 is loaded with the Mac address of the ed_ReadPacket code inside ether_data, and the protocol handler is called with Execute68k() 5. The protocol handler will eventually try to read the packet data with a "jsr (a4)" or "jsr 2(a4)" 6. This will execute an M68K_EMUL_OP_ETHER_READ_PACKET opcode 7. The EtherReadPacket() opcode handling routine will copy the requested part of the packet data to Mac RAM using the pointer and length which are still in a0/d1 For a more detailed description of the Ethernet driver, see the book "Inside AppleTalk". 6.13. System-dependant device access ------------------------------------ The method for accessing floppy drives, hard disks, CD-ROM drives and files vary greatly between different operating systems. To make Basilisk II easily portable, all device I/O is made via the functions declared in "sys.h" and implemented by the (system-dependant) "sys_*.cpp" modules which provides a standard, Unix-like interface to all kinds of devices. 6.14. User interface strings ---------------------------- To aid in localization, all user interface strings of Basilisk II are collected in "user_strings.cpp" (for common strings) and "user_strings_*.cpp" (for platform-specific strings), and accessed via the GetString() function. This way, Basilisk II may be easily translated to different languages. 6.15. Preferences management ---------------------------- The module "prefs.cpp" handles user preferences in a system-independant way. Preferences items are accessed with the PrefsAdd*(), PrefsReplace*() and PrefsFind*() functions and stored in human-readable and editable text files on disk. There are two lists of available preferences items. The first one, common_prefs_items, is defined in "prefs_items.cpp" and lists items which are available on all systems. The second one, platform_prefs_items, is defined in "prefs_*.cpp" and lists the prefs items which are specific to a certain platform. The "prefs_editor_*.cpp" module provides a graphical user interface for setting the preferences so users won't have to edit the preferences file manually. 7. Porting Basilisk II ---------------------- Porting Basilisk II to a new platform should not be hard. These are the steps involved in the process: 1. Create a new directory inside the "src" directory for your platform. If your platform comes in several "flavours" that require adapted files, you should consider creating subdirectories inside the platform directory. All files needed for your port must be placed inside the new directory. Don't scatter platform-dependant files across the "src" hierarchy. 2. Decide in which mode (virtual addressing, real addressing or native CPU) Basilisk II will run. 3. Create a "sysdeps.h" file which defines the mode and system-dependant data types and memory access functions. Things which are used in Basilisk but missing on your platform (such as endianess macros) should also be defined here. 4. Implement the system-specific parts of Basilisk: main_*.cpp, sys_*.cpp, prefs_*.cpp, prefs_editor_*.cpp, xpram_*.cpp, timer_*.cpp, audio_*.cpp, video_*.cpp, serial_*.cpp, ether_*.cpp, scsi_*.cpp and clip_*.cpp You may want to take the skeleton implementations in the "dummy" directory as a starting point and look at the implementation for other platforms before writing your own. 5. Important things to remember: - Use the ReadMacInt*() and WriteMacInt*() functions from "cpu_emulation.h" to access Mac memory - Use the ntohs() etc. macros to convert endianess when accessing Mac memory directly - Don't modify any source files outside of your platform directory unless you really, really have to. Instead of adding "#ifdef PLATFORM" blocks to one of the platform-independant source files, you should contact me so that we may find a more elegant and more portable solution. 6. Coding style: indent -kr -ts4 Christian Bauer <Christian.Bauer@uni-mainz.de>